/*******************************************************************************
 * Copyright (c) 2001, 2002 Boris Pruessmann and others. All rights reserved.
 * This program and the accompanying materials are made available under the
 * terms of the Common Public License v0.5 which accompanies this distribution,
 * and is available at http://www.eclipse.org/legal/cpl-v05.html
 * 
 * Contributors: Boris Pruessmann - Initial implementation.
 ******************************************************************************/
package net.sourceforge.perforce.core.api;

import net.sourceforge.perforce.core.PerforceCorePlugin;
import net.sourceforge.perforce.core.PerforceException;

import org.eclipse.core.resources.IProject;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.QualifiedName;

import java.util.Map;

/**
 * This interface describes the public API of the ServerManager which is used to
 * manage perforce servers known to the plugin.
 * 
 * @version $Revision: 488 $
 * @author <a href="mailto:bpruessmann@users.sourceforge.net">Boris
 *         Pruessmann</a>
 */
public interface IPerforceServerManager {
  //----------------------------------------------------------------------------
  // ------- Constants

  /** Name of the persistent property used to attach a server to a project. */
  QualifiedName QN_PERSISTENT_SERVER = new QualifiedName(PerforceCorePlugin.ID, "server");

  //----------------------------------------------------------------------------
  // --------- Methods

  /**
   * Call this method to create a new PerforceServer. The server is not added to
   * the control of the server manager. Checks whether there is already a server
   * object with the same (calculated) unique name.
   * 
   * @param properties containing connection data.
   * @return the new perforce server.
   * 
   * @throws PerforceException in case of an error.
   */
  IPerforceServer createPerforceServer(Map<String, ?> properties) throws PerforceException;

  /**
   * Adds the given server object to the control of the manager.
   * 
   * @param server to be added.
   * 
   * @throws PerforceException in case of an unexpected error.
   */
  void addPerforceServer(IPerforceServer server) throws PerforceException;

  /**
   * Removed the given server object from the control of the manager.
   * 
   * @param server the server to remove.
   * 
   * @throws PerforceException in case of an error.
   */
  void removePerforceServer(IPerforceServer server) throws PerforceException;

  /**
   * Call this method to get an array of registered perforce servers.
   * 
   * @return array of servers.
   */
  IPerforceServer[] getPerforceServers();

  /**
   * Call this method to retrieve a properties object containing the system
   * defaults for the information needed to create a server object.
   * 
   * @return properties containing defaults.
   */
  Map<String, Object> getConnectionDefaults();

  /**
   * Returns a set of default connection properties as would be returned by
   * {@link #getConnectionDefaults()}.
   * 
   * <p>
   * Values will be overridden by those found in a "p4 config" file if:
   * <ul>
   * <li>the "P4CONFIG" environmental variable is defined</li>
   * <li>a file with the name specified in "P4CONFIG` is found in the directory
   * specified in the supplied path or one of the parent directories</li>
   * 
   * See
   * "http://www.perforce.com/perforce/doc.042/manuals/cmdref/env.P4CONFIG.html"
   * for details.
   * 
   * @return proeprties containing defaults.
   */
  Map<String, Object> getConnectionDefaults(IPath path);

  /**
   * Associates the given project and server.
   * 
   * @param project the project to be associated.
   * @param server the perforce server.
   * @param monitor used for progress feedback.
   * 
   * @throws PerforceException in case of an error.
   */
  void setSharing(IProject project, IPerforceServer server, IProgressMonitor monitor)
      throws PerforceException;

  /**
   * Call this to retrieve the PerforceServer that is (potentially) responsible
   * for the given resource.
   * 
   * @param resource the resource.
   * @return the responsible server or null.
   * 
   * @throws PerforceException in case of an error.
   */
  IPerforceServer getPerforceServer(IResource resource) throws PerforceException;

  /**
   * Called to retrieve the IPerforceServer for the given unique name
   * 
   * @param uniqueName the unique name of the server.
   * @return the responsible server or null.
   */
  IPerforceServer getPerforceServer(String uniqueName);

  /**
   * Returns a list of projects that reference the given server.
   * 
   * @param server the server.
   * @return array of referencing projects.
   * 
   * @throws PerforceException in case of an error.
   */
  IProject[] getReferencingProjects(IPerforceServer server) throws PerforceException;

  /**
   * Addes the given listener to the notification list.
   * 
   * @param listener the listener.
   */
  void addPerforceListener(IPerforceListener listener);

  /**
   * Removes the given listener from the notification list.
   * 
   * @param listener the listener.
   */
  void removePerforceListener(IPerforceListener listener);

  /**
   * Stores a snapshot of the manager's current state.
   * 
   * @throws PerforceException in case of an error.
   */
  void performSnapshot() throws PerforceException;
}
